TypeScript Compiler API: Освоение манипуляций с AST и трансформации кода

TypeScript Compiler API предоставляет мощный интерфейс для анализа, манипуляции и генерации кода TypeScript и JavaScript. В основе его работы лежит Абстрактное синтаксическое дерево (AST) — структурированное представление вашего исходного кода. Понимание работы с AST открывает возможности для создания продвинутых инструментов, таких как линтеры, форматировщики кода, статические анализаторы и пользовательские генераторы кода.

Что такое TypeScript Compiler API?

TypeScript Compiler API — это набор интерфейсов и функций TypeScript, которые раскрывают внутреннюю работу компилятора TypeScript. Он позволяет разработчикам программно взаимодействовать с процессом компиляции, выходя за рамки простого компилирования кода. Вы можете использовать его для:

• Анализа кода: Изучение структуры кода, выявление потенциальных проблем и извлечение семантической информации.
• Трансформации кода: Изменение существующего кода, добавление новых функций или автоматическая рефакторинг кода.
• Генерации кода: Создание нового кода с нуля на основе шаблонов или другого ввода.

Этот API необходим для создания сложных инструментов разработки, которые повышают качество кода, автоматизируют повторяющиеся задачи и увеличивают продуктивность разработчиков.

Понимание Абстрактного синтаксического дерева (AST)

AST — это древовидное представление структуры вашего кода. Каждый узел в дереве представляет собой синтаксическую конструкцию, такую как объявление переменной, вызов функции или оператор управления потоком. TypeScript Compiler API предоставляет инструменты для обхода AST, изучения его узлов и их изменения.

Рассмотрим простой код TypeScript:

function greet(name: string): string {
  return `Hello, ${name}!`;
}

console.log(greet("World"));

AST для этого кода будет представлять объявление функции, оператор возврата, шаблонный литерал, вызов console.log и другие элементы кода. Визуализация AST может быть сложной, но такие инструменты, как AST explorer (astexplorer.net), могут помочь. Эти инструменты позволяют вводить код и видеть соответствующее AST в удобном формате. Использование AST Explorer поможет вам понять структуру кода, с которой вы будете работать.

Основные типы узлов AST

TypeScript Compiler API определяет различные типы узлов AST, каждый из которых представляет собой различную синтаксическую конструкцию. Вот некоторые распространенные типы узлов:

• SourceFile: Представляет весь файл TypeScript.
• FunctionDeclaration: Представляет определение функции.
• VariableDeclaration: Представляет объявление переменной.
• Identifier: Представляет идентификатор (например, имя переменной, имя функции).
• StringLiteral: Представляет строковый литерал.
• CallExpression: Представляет вызов функции.
• ReturnStatement: Представляет оператор возврата.

Каждый тип узла имеет свойства, которые предоставляют информацию о соответствующем элементе кода. Например, узел `FunctionDeclaration` может иметь свойства для имени, параметров, типа возвращаемого значения и тела.

Начало работы с Compiler API

Чтобы начать использовать Compiler API, вам нужно установить TypeScript и иметь базовое понимание синтаксиса TypeScript. Вот простой пример, демонстрирующий, как прочитать файл TypeScript и вывести его AST:

import * as ts from "typescript";
import * as fs from "fs";

const fileName = "example.ts";
const sourceCode = fs.readFileSync(fileName, "utf8");

const sourceFile = ts.createSourceFile(
  fileName,
  sourceCode,
  ts.ScriptTarget.ES2015, // Целевая версия ECMAScript
  true // SetParentNodes: true для сохранения ссылок на родительские узлы в AST
);

function printAST(node: ts.Node, indent = 0) {
  const indentStr = "  ".repeat(indent);
  console.log(`${indentStr}${ts.SyntaxKind[node.kind]}`);

  node.forEachChild(child => printAST(child, indent + 1));
}

printAST(sourceFile);

Пояснение:

1. Импорт модулей: Импортирует модуль `typescript` и модуль `fs` для операций с файловой системой.
2. Чтение исходного файла: Читает содержимое файла TypeScript с именем `example.ts`. Вам потребуется создать файл `example.ts` для работы этого кода.
3. Создание SourceFile: Создает объект `SourceFile`, который представляет корень AST. Функция `ts.createSourceFile` анализирует исходный код и генерирует AST.
4. Печать AST: Определяет рекурсивную функцию `printAST`, которая обходит AST и выводит тип каждого узла.
5. Вызов printAST: Вызывает `printAST` для начала вывода AST из корневого узла `SourceFile`.

Чтобы запустить этот код, сохраните его как файл `.ts` (например, `ast-example.ts`), создайте файл `example.ts` с каким-либо кодом TypeScript, а затем скомпилируйте и запустите код:

tsc ast-example.ts
node ast-example.js

Это выведет AST вашего файла `example.ts` в консоль. Вывод покажет иерархию узлов и их типы. Например, он может показать `FunctionDeclaration`, `Identifier`, `Block` и другие типы узлов.

Обход AST

Compiler API предоставляет несколько способов обхода AST. Самый простой — использование метода `forEachChild`, как показано в предыдущем примере. Этот метод посещает каждый дочерний узел заданного узла.

Для более сложных сценариев обхода вы можете использовать шаблон «Посетитель» (Visitor). Посетитель — это объект, который определяет методы, вызываемые для конкретных типов узлов. Это позволяет настраивать процесс обхода и выполнять действия в зависимости от типа узла.

import * as ts from "typescript";
import * as fs from "fs";

const fileName = "example.ts";
const sourceCode = fs.readFileSync(fileName, "utf8");

const sourceFile = ts.createSourceFile(
  fileName,
  sourceCode,
  ts.ScriptTarget.ES2015,
  true
);

class IdentifierVisitor {
  visit(node: ts.Node) {
    if (ts.isIdentifier(node)) {
      console.log(`Найден идентификатор: ${node.text}`);
    }

    ts.forEachChild(node, n => this.visit(n));
  }
}

const visitor = new IdentifierVisitor();
visitor.visit(sourceFile);

Пояснение:

1. Класс IdentifierVisitor: Определяет класс `IdentifierVisitor` с методом `visit`.
2. Метод Visit: Метод `visit` проверяет, является ли текущий узел `Identifier`. Если да, он выводит текст идентификатора. Затем он рекурсивно вызывает `ts.forEachChild` для посещения дочерних узлов.
3. Создание посетителя: Создает экземпляр `IdentifierVisitor`.
4. Начало обхода: Вызывает метод `visit` для `SourceFile`, чтобы начать обход.

Этот пример демонстрирует, как найти все идентификаторы в AST. Вы можете адаптировать этот шаблон для поиска других типов узлов и выполнения различных действий.

Трансформация AST

Истинная сила Compiler API заключается в его способности трансформировать AST. Вы можете изменять AST для изменения структуры и поведения вашего кода. Это основа для инструментов рефакторинга кода, генераторов кода и других продвинутых инструментов.

Для трансформации AST вам нужно использовать функцию `ts.transform`. Эта функция принимает `SourceFile` и список функций `TransformerFactory`. `TransformerFactory` — это функция, которая принимает `TransformationContext` и возвращает функцию `Transformer`. Функция `Transformer` отвечает за посещение и трансформацию узлов в AST.

Вот простой пример, демонстрирующий, как добавить комментарий в начало файла TypeScript:

import * as ts from "typescript";
import * as fs from "fs";

const fileName = "example.ts";
const sourceCode = fs.readFileSync(fileName, "utf8");

const sourceFile = ts.createSourceFile(
  fileName,
  sourceCode,
  ts.ScriptTarget.ES2015,
  true
);

const transformerFactory: ts.TransformerFactory = context => {
  return transformer => {
    return node => {
      if (ts.isSourceFile(node)) {
        // Создать ведущий комментарий
        const comment = ts.addSyntheticLeadingComment(
          node,
          ts.SyntaxKind.MultiLineCommentTrivia,
          " Этот файл был автоматически трансформирован ",
          true // hasTrailingNewLine
        );

        return node;
      }

      return node;
    };
  };
};

const { transformed } = ts.transform(sourceFile, [transformerFactory]);

const printer = ts.createPrinter({
  newLine: ts.NewLineKind.LineFeed
});

const result = printer.printFile(transformed[0]);

fs.writeFileSync("example.transformed.ts", result);

Пояснение:

1. TransformerFactory: Определяет функцию `TransformerFactory`, которая возвращает функцию `Transformer`.
2. Transformer: Функция `Transformer` проверяет, является ли текущий узел `SourceFile`. Если да, она добавляет ведущий комментарий к узлу с помощью `ts.addSyntheticLeadingComment`.
3. ts.transform: Вызывает `ts.transform` для применения трансформации к `SourceFile`.
4. Printer: Создает объект `Printer` для генерации кода из трансформированного AST.
5. Печать и запись: Печатает трансформированный код и записывает его в новый файл с именем `example.transformed.ts`.

Этот пример демонстрирует простую трансформацию, но вы можете использовать тот же шаблон для выполнения более сложных трансформаций, таких как рефакторинг кода, добавление логгирующих операторов или генерация документации.

Продвинутые методы трансформации

Вот некоторые продвинутые методы трансформации, которые вы можете использовать с Compiler API:

• Создание новых узлов: Используйте функции `ts.createXXX` для создания новых узлов AST. Например, `ts.createVariableDeclaration` создает новый узел объявления переменной.
• Замена узлов: Заменяйте существующие узлы новыми, используя функцию `ts.visitEachChild`.
• Добавление узлов: Добавляйте новые узлы в AST, используя функции `ts.updateXXX`. Например, `ts.updateBlock` обновляет оператор блока новыми операторами.
• Удаление узлов: Удаляйте узлы из AST, возвращая `undefined` из функции-трансформатора.

Генерация кода

После трансформации AST вам нужно будет сгенерировать из него код. Compiler API предоставляет для этой цели объект `Printer`. `Printer` принимает AST и генерирует его строковое представление.

Функция `ts.createPrinter` создает объект `Printer`. Вы можете настроить принтер с различными параметрами, такими как символ новой строки для использования и следует ли выводить комментарии.

Метод `printer.printFile` принимает `SourceFile` и возвращает строковое представление кода. Затем вы можете записать эту строку в файл.

Практическое применение Compiler API

TypeScript Compiler API имеет множество практических применений в разработке программного обеспечения. Вот несколько примеров:

• Линтеры: Создание пользовательских линтеров для обеспечения стандартов кодирования и выявления потенциальных проблем в вашем коде.
• Форматировщики кода: Создание форматировщиков кода для автоматического форматирования вашего кода в соответствии с определенным руководством по стилю.
• Статические анализаторы: Разработка статических анализаторов для обнаружения ошибок, уязвимостей безопасности и узких мест производительности в вашем коде.
• Генераторы кода: Генерация кода из шаблонов или других входных данных, автоматизация повторяющихся задач и сокращение шаблонного кода. Например, генерация клиентских API или схем баз данных из файла описания.
• Инструменты рефакторинга: Создание инструментов рефакторинга для автоматического переименования переменных, извлечения функций или перемещения кода между файлами.
• Автоматизация интернационализации (i18n): Автоматическое извлечение переводимых строк из вашего кода TypeScript и генерация файлов локализации для разных языков. Например, инструмент может сканировать код на наличие строк, передаваемых в функцию `translate()`, и автоматически добавлять их в файл ресурсов перевода.

Пример: создание простого линтера

Давайте создадим простой линтер, который проверяет неиспользуемые переменные в коде TypeScript. Этот линтер будет выявлять переменные, которые объявлены, но никогда не используются.

import * as ts from "typescript";
import * as fs from "fs";

const fileName = "example.ts";
const sourceCode = fs.readFileSync(fileName, "utf8");

const sourceFile = ts.createSourceFile(
  fileName,
  sourceCode,
  ts.ScriptTarget.ES2015,
  true
);

function findUnusedVariables(sourceFile: ts.SourceFile) {
  const usedVariables = new Set();

  function visit(node: ts.Node) {
    if (ts.isIdentifier(node)) {
      usedVariables.add(node.text);
    }

    ts.forEachChild(node, visit);
  }

  visit(sourceFile);

  const unusedVariables: string[] = [];

  function checkVariableDeclaration(node: ts.Node) {
    if (ts.isVariableDeclaration(node) && node.name && ts.isIdentifier(node.name)) {
      const variableName = node.name.text;
      if (!usedVariables.has(variableName)) {
        unusedVariables.push(variableName);
      }
    }

    ts.forEachChild(node, checkVariableDeclaration);
  }

  checkVariableDeclaration(sourceFile);

  return unusedVariables;
}

const unusedVariables = findUnusedVariables(sourceFile);

if (unusedVariables.length > 0) {
  console.log("Неиспользуемые переменные:");
  unusedVariables.forEach(variable => console.log(`- ${variable}`));
} else {
  console.log("Неиспользуемые переменные не найдены.");
}

Пояснение:

1. Функция findUnusedVariables: Определяет функцию `findUnusedVariables`, которая принимает `SourceFile` в качестве входных данных.
2. Множество usedVariables: Создает `Set` для хранения имен используемых переменных.
3. Функция visit: Определяет рекурсивную функцию `visit`, которая обходит AST и добавляет имена всех идентификаторов в множество `usedVariables`.
4. Функция checkVariableDeclaration: Определяет рекурсивную функцию `checkVariableDeclaration`, которая проверяет, не используется ли объявление переменной. Если нет, она добавляет имя переменной в массив `unusedVariables`.
5. Возврат unusedVariables: Возвращает массив, содержащий имена неиспользуемых переменных.
6. Вывод: Выводит неиспользуемые переменные в консоль.

Этот пример демонстрирует простой линтер. Вы можете расширить его для проверки других стандартов кодирования и выявления других потенциальных проблем в вашем коде. Например, вы можете проверять неиспользуемые импорты, слишком сложные функции или потенциальные уязвимости безопасности. Ключ в том, чтобы понять, как обходить AST и идентифицировать интересующие вас типы узлов.

Лучшие практики и соображения

• Поймите AST: Потратьте время на понимание структуры AST. Используйте такие инструменты, как AST explorer, для визуализации AST вашего кода.
• Используйте Type Guards: Используйте Type Guards (`ts.isXXX`), чтобы убедиться, что вы работаете с правильными типами узлов.
• Учитывайте производительность: Трансформации AST могут быть вычислительно затратными. Оптимизируйте свой код, чтобы минимизировать количество узлов, которые вы посещаете и трансформируете.
• Обработка ошибок: Грамотно обрабатывайте ошибки. Compiler API может выдавать исключения, если вы попытаетесь выполнить недопустимые операции с AST.
• Тщательное тестирование: Тщательно тестируйте свои трансформации, чтобы убедиться, что они дают желаемые результаты и не вносят новых ошибок.
• Используйте существующие библиотеки: Рассмотрите возможность использования существующих библиотек, которые предоставляют более высокоуровневые абстракции над Compiler API. Эти библиотеки могут упростить распространенные задачи и уменьшить объем кода, который вам нужно написать. Примеры включают `ts-morph` и `typescript-eslint`.

Заключение

TypeScript Compiler API — это мощный инструмент для создания продвинутых инструментов разработки. Понимая, как работать с AST, вы можете создавать линтеры, форматировщики кода, статические анализаторы и другие инструменты, которые улучшают качество кода, автоматизируют повторяющиеся задачи и повышают продуктивность разработчиков. Хотя API может быть сложным, преимущества освоения его значительны. Это подробное руководство предоставляет основу для изучения и эффективного использования Compiler API в ваших проектах. Не забывайте использовать такие инструменты, как AST Explorer, тщательно обрабатывать типы узлов и тщательно тестировать свои трансформации. С практикой и целеустремленностью вы сможете раскрыть весь потенциал TypeScript Compiler API и создавать инновационные решения для ландшафта разработки программного обеспечения.

Дальнейшее изучение:

• Документация TypeScript Compiler API: [https://github.com/microsoft/TypeScript/wiki/Using-the-Compiler-API](https://github.com/microsoft/TypeScript/wiki/Using-the-Compiler-API)
• AST Explorer: [https://astexplorer.net/](https://astexplorer.net/)
• Библиотека ts-morph: [https://ts-morph.com/](https://ts-morph.com/)
• typescript-eslint: [https://typescript-eslint.io/](https://typescript-eslint.io/)